<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Advanced Zend_Form Usage - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.form.advanced.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.form.advanced.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.form.i18n.html">Internationalization of Zend_Form</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.form.html">Zend_Form</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.gdata.html">Zend_Gdata</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.form.advanced" class="section"><div class="info"><h1 class="title">Advanced Zend_Form Usage</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Form</span> has a wealth of functionality, much of it aimed
        at experienced developers. This chapter aims to document some of this
        functionality with examples and use cases.
    </p>

    <div class="section" id="zend.form.advanced.arrayNotation"><div class="info"><h1 class="title">Array Notation</h1></div>
        

        <p class="para">
            Many experienced web developers like to group related form elements
            using array notation in the element names. For example, if you have
            two addresses you wish to capture, a shipping and a billing address,
            you may have identical elements; by grouping them in an array, you
            can ensure they are captured separately. Take the following form,
            for example:
        </p>

        <pre class="programlisting brush: html">
&lt;form&gt;
    &lt;fieldset&gt;
        &lt;legend&gt;Shipping Address&lt;/legend&gt;
        &lt;dl&gt;
            &lt;dt&gt;&lt;label for=&quot;recipient&quot;&gt;Ship to:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;recipient&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;address&quot;&gt;Address:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;address&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;municipality&quot;&gt;City:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;municipality&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;province&quot;&gt;State:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;province&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;postal&quot;&gt;Postal Code:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;postal&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;
        &lt;/dl&gt;
    &lt;/fieldset&gt;

    &lt;fieldset&gt;
        &lt;legend&gt;Billing Address&lt;/legend&gt;
        &lt;dl&gt;
            &lt;dt&gt;&lt;label for=&quot;payer&quot;&gt;Bill To:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;payer&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;address&quot;&gt;Address:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;address&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;municipality&quot;&gt;City:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;municipality&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;province&quot;&gt;State:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;province&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;postal&quot;&gt;Postal Code:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;postal&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;
        &lt;/dl&gt;
    &lt;/fieldset&gt;

    &lt;dl&gt;
        &lt;dt&gt;&lt;label for=&quot;terms&quot;&gt;I agree to the Terms of Service&lt;/label&gt;&lt;/dt&gt;
        &lt;dd&gt;&lt;input name=&quot;terms&quot; type=&quot;checkbox&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

        &lt;dt&gt;&lt;/dt&gt;
        &lt;dd&gt;&lt;input name=&quot;save&quot; type=&quot;submit&quot; value=&quot;Save&quot; /&gt;&lt;/dd&gt;
    &lt;/dl&gt;
&lt;/form&gt;
</pre>


        <p class="para">
            In this example, the billing and shipping address contain some
            identical fields, which means one would overwrite the other. We can
            solve this solution using array notation:
        </p>

        <pre class="programlisting brush: html">
&lt;form&gt;
    &lt;fieldset&gt;
        &lt;legend&gt;Shipping Address&lt;/legend&gt;
        &lt;dl&gt;
            &lt;dt&gt;&lt;label for=&quot;shipping-recipient&quot;&gt;Ship to:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;shipping[recipient]&quot; id=&quot;shipping-recipient&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;shipping-address&quot;&gt;Address:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;shipping[address]&quot; id=&quot;shipping-address&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;shipping-municipality&quot;&gt;City:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;shipping[municipality]&quot; id=&quot;shipping-municipality&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;shipping-province&quot;&gt;State:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;shipping[province]&quot; id=&quot;shipping-province&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;shipping-postal&quot;&gt;Postal Code:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;shipping[postal]&quot; id=&quot;shipping-postal&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;
        &lt;/dl&gt;
    &lt;/fieldset&gt;

    &lt;fieldset&gt;
        &lt;legend&gt;Billing Address&lt;/legend&gt;
        &lt;dl&gt;
            &lt;dt&gt;&lt;label for=&quot;billing-payer&quot;&gt;Bill To:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;billing[payer]&quot; id=&quot;billing-payer&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;billing-address&quot;&gt;Address:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;billing[address]&quot; id=&quot;billing-address&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;billing-municipality&quot;&gt;City:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;billing[municipality]&quot; id=&quot;billing-municipality&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;billing-province&quot;&gt;State:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;billing[province]&quot; id=&quot;billing-province&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

            &lt;dt&gt;&lt;label for=&quot;billing-postal&quot;&gt;Postal Code:&lt;/label&gt;&lt;/dt&gt;
            &lt;dd&gt;&lt;input name=&quot;billing[postal]&quot; id=&quot;billing-postal&quot;
                type=&quot;text&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;
        &lt;/dl&gt;
    &lt;/fieldset&gt;

    &lt;dl&gt;
        &lt;dt&gt;&lt;label for=&quot;terms&quot;&gt;I agree to the Terms of Service&lt;/label&gt;&lt;/dt&gt;
        &lt;dd&gt;&lt;input name=&quot;terms&quot; type=&quot;checkbox&quot; value=&quot;&quot; /&gt;&lt;/dd&gt;

        &lt;dt&gt;&lt;/dt&gt;
        &lt;dd&gt;&lt;input name=&quot;save&quot; type=&quot;submit&quot; value=&quot;Save&quot; /&gt;&lt;/dd&gt;
    &lt;/dl&gt;
&lt;/form&gt;
</pre>


        <p class="para">
            In the above sample, we now get separate addresses. In the submitted
            form, we&#039;ll now have three elements, the &#039;save&#039; element for the
            submit, and then two arrays, &#039;shipping&#039; and &#039;billing&#039;, each with
            keys for their various elements.
        </p>

        <p class="para">
            <span class="classname">Zend_Form</span> attempts to automate this process with its
            <a href="zend.form.forms.html#zend.form.forms.subforms" class="link">sub forms</a>. By
            default, sub forms render using the array notation as shown in the
            previous <acronym class="acronym">HTML</acronym> form listing, complete with ids. The array name is
            based on the sub form name, with the keys based on the elements
            contained in the sub form. Sub forms may be nested arbitrarily deep,
            and this will create nested arrays to reflect the structure.
            Additionally, the various validation routines in
            <span class="classname">Zend_Form</span> honor the array structure, ensuring that your
            form validates correctly, no matter how arbitrarily deep you nest
            your sub forms. You need do nothing to benefit from this; this
            behaviour is enabled by default.
        </p>

        <p class="para">
            Additionally, there are facilities that allow you to turn on array
            notation conditionally, as well as specify the specific array to
            which an element or collection belongs:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                     <span class="methodname">Zend_Form::setIsArray($flag)</span>: By setting the
                    flag <b><tt>TRUE</tt></b>, you can indicate that an entire form should be
                    treated as an array. By default, the form&#039;s name will be
                    used as the name of the array, unless
                     <span class="methodname">setElementsBelongTo()</span> has been called. If the
                    form has no specified name, or if
                     <span class="methodname">setElementsBelongTo()</span> has not been set, this
                    flag will be ignored (as there is no array name to which
                    the elements may belong).
                </p>

                <p class="para">
                    You may determine if a form is being treated as an array
                    using the  <span class="methodname">isArray()</span> accessor.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                     <span class="methodname">Zend_Form::setElementsBelongTo($array)</span>:
                    Using this method, you can specify the name of an array to
                    which all elements of the form belong. You can determine the
                    name using the  <span class="methodname">getElementsBelongTo()</span> accessor.
                </p>
            </li>
        </ul>

        <p class="para">
            Additionally, on the element level, you can specify individual
            elements may belong to particular arrays using
             <span class="methodname">Zend_Form_Element::setBelongsTo()</span> method.
            To discover what this value is -- whether set explicitly or
            implicitly via the form -- you may use the
             <span class="methodname">getBelongsTo()</span> accessor.
        </p>
    </div>

    <div class="section" id="zend.form.advanced.multiPage"><div class="info"><h1 class="title">Multi-Page Forms</h1></div>
        

        <p class="para">
            Currently, Multi-Page forms are not officially supported in
            <span class="classname">Zend_Form</span>; however, most support for implementing them
            is available and can be utilized with a little extra tooling.
        </p>

        <p class="para">
            The key to creating a multi-page form is to utilize sub forms, but
            to display only one such sub form per page. This allows you to
            submit a single sub form at a time and validate it, but not process
            the form until all sub forms are complete.
        </p>

        <div class="example" id="zend.form.advanced.multiPage.registration"><div class="info"><p><b>Example #1 Registration Form Example</b></p></div>
            

            <div class="example-contents"><p>
                Let&#039;s use a registration form as an example. For our purposes,
                we want to capture the desired username and password on the
                first page, then the user&#039;s metadata -- given name, family name,
                and location -- and finally allow them to decide what mailing
                lists, if any, they wish to subscribe to.
            </p></div>

            <div class="example-contents"><p>
                First, let&#039;s create our own form, and define several sub forms
                within it:
            </p></div>

            <pre class="programlisting brush: php">
class My_Form_Registration extends Zend_Form
{
    public function init()
    {
        // Create user sub form: username and password
        $user = new Zend_Form_SubForm();
        $user-&gt;addElements(array(
            new Zend_Form_Element_Text(&#039;username&#039;, array(
                &#039;required&#039;   =&gt; true,
                &#039;label&#039;      =&gt; &#039;Username:&#039;,
                &#039;filters&#039;    =&gt; array(&#039;StringTrim&#039;, &#039;StringToLower&#039;),
                &#039;validators&#039; =&gt; array(
                    &#039;Alnum&#039;,
                    array(&#039;Regex&#039;,
                          false,
                          array(&#039;/^[a-z][a-z0-9]{2,}$/&#039;))
                )
            )),

            new Zend_Form_Element_Password(&#039;password&#039;, array(
                &#039;required&#039;   =&gt; true,
                &#039;label&#039;      =&gt; &#039;Password:&#039;,
                &#039;filters&#039;    =&gt; array(&#039;StringTrim&#039;),
                &#039;validators&#039; =&gt; array(
                    &#039;NotEmpty&#039;,
                    array(&#039;StringLength&#039;, false, array(6))
                )
            )),
        ));

        // Create demographics sub form: given name, family name, and
        // location
        $demog = new Zend_Form_SubForm();
        $demog-&gt;addElements(array(
            new Zend_Form_Element_Text(&#039;givenName&#039;, array(
                &#039;required&#039;   =&gt; true,
                &#039;label&#039;      =&gt; &#039;Given (First) Name:&#039;,
                &#039;filters&#039;    =&gt; array(&#039;StringTrim&#039;),
                &#039;validators&#039; =&gt; array(
                    array(&#039;Regex&#039;,
                          false,
                          array(&#039;/^[a-z][a-z0-9., \&#039;-]{2,}$/i&#039;))
                )
            )),

            new Zend_Form_Element_Text(&#039;familyName&#039;, array(
                &#039;required&#039;   =&gt; true,
                &#039;label&#039;      =&gt; &#039;Family (Last) Name:&#039;,
                &#039;filters&#039;    =&gt; array(&#039;StringTrim&#039;),
                &#039;validators&#039; =&gt; array(
                    array(&#039;Regex&#039;,
                          false,
                          array(&#039;/^[a-z][a-z0-9., \&#039;-]{2,}$/i&#039;))
                )
            )),

            new Zend_Form_Element_Text(&#039;location&#039;, array(
                &#039;required&#039;   =&gt; true,
                &#039;label&#039;      =&gt; &#039;Your Location:&#039;,
                &#039;filters&#039;    =&gt; array(&#039;StringTrim&#039;),
                &#039;validators&#039; =&gt; array(
                    array(&#039;StringLength&#039;, false, array(2))
                )
            )),
        ));

        // Create mailing lists sub form
        $listOptions = array(
            &#039;none&#039;        =&gt; &#039;No lists, please&#039;,
            &#039;fw-general&#039;  =&gt; &#039;Zend Framework General List&#039;,
            &#039;fw-mvc&#039;      =&gt; &#039;Zend Framework MVC List&#039;,
            &#039;fw-auth&#039;     =&gt; &#039;Zend Framwork Authentication and ACL List&#039;,
            &#039;fw-services&#039; =&gt; &#039;Zend Framework Web Services List&#039;,
        );
        $lists = new Zend_Form_SubForm();
        $lists-&gt;addElements(array(
            new Zend_Form_Element_MultiCheckbox(&#039;subscriptions&#039;, array(
                &#039;label&#039;        =&gt;
                    &#039;Which lists would you like to subscribe to?&#039;,
                &#039;multiOptions&#039; =&gt; $listOptions,
                &#039;required&#039;     =&gt; true,
                &#039;filters&#039;      =&gt; array(&#039;StringTrim&#039;),
                &#039;validators&#039;   =&gt; array(
                    array(&#039;InArray&#039;,
                          false,
                          array(array_keys($listOptions)))
                )
            )),
        ));

        // Attach sub forms to main form
        $this-&gt;addSubForms(array(
            &#039;user&#039;  =&gt; $user,
            &#039;demog&#039; =&gt; $demog,
            &#039;lists&#039; =&gt; $lists
        ));
    }
}
</pre>


            <div class="example-contents"><p>
                Note that there are no submit buttons, and that we have done
                nothing with the sub form decorators -- which means that by
                default they will be displayed as fieldsets. We will need to be
                able to override these as we display each individual sub form,
                and add in submit buttons so we can actually process them --
                which will also require action and method properties. Let&#039;s add
                some scaffolding to our class to provide that information:
            </p></div>

            <pre class="programlisting brush: php">
class My_Form_Registration extends Zend_Form
{
    // ...

    /**
     * Prepare a sub form for display
     *
     * @param  string|Zend_Form_SubForm $spec
     * @return Zend_Form_SubForm
     */
    public function prepareSubForm($spec)
    {
        if (is_string($spec)) {
            $subForm = $this-&gt;{$spec};
        } elseif ($spec instanceof Zend_Form_SubForm) {
            $subForm = $spec;
        } else {
            throw new Exception(&#039;Invalid argument passed to &#039; .
                                __FUNCTION__ . &#039;()&#039;);
        }
        $this-&gt;setSubFormDecorators($subForm)
             -&gt;addSubmitButton($subForm)
             -&gt;addSubFormActions($subForm);
        return $subForm;
    }

    /**
     * Add form decorators to an individual sub form
     *
     * @param  Zend_Form_SubForm $subForm
     * @return My_Form_Registration
     */
    public function setSubFormDecorators(Zend_Form_SubForm $subForm)
    {
        $subForm-&gt;setDecorators(array(
            &#039;FormElements&#039;,
            array(&#039;HtmlTag&#039;, array(&#039;tag&#039; =&gt; &#039;dl&#039;,
                                   &#039;class&#039; =&gt; &#039;zend_form&#039;)),
            &#039;Form&#039;,
        ));
        return $this;
    }

    /**
     * Add a submit button to an individual sub form
     *
     * @param  Zend_Form_SubForm $subForm
     * @return My_Form_Registration
     */
    public function addSubmitButton(Zend_Form_SubForm $subForm)
    {
        $subForm-&gt;addElement(new Zend_Form_Element_Submit(
            &#039;save&#039;,
            array(
                &#039;label&#039;    =&gt; &#039;Save and continue&#039;,
                &#039;required&#039; =&gt; false,
                &#039;ignore&#039;   =&gt; true,
            )
        ));
        return $this;
    }

    /**
     * Add action and method to sub form
     *
     * @param  Zend_Form_SubForm $subForm
     * @return My_Form_Registration
     */
    public function addSubFormActions(Zend_Form_SubForm $subForm)
    {
        $subForm-&gt;setAction(&#039;/registration/process&#039;)
                -&gt;setMethod(&#039;post&#039;);
        return $this;
    }
}
</pre>


            <div class="example-contents"><p>
                Next, we need to add some scaffolding in our action controller,
                and have several considerations. First, we need to make sure we
                persist form data between requests, so that we can determine
                when to quit. Second, we need some logic to determine what form
                segments have already been submitted, and what sub form to
                display based on that information. We&#039;ll use
                <span class="classname">Zend_Session_Namespace</span> to persist data, which will
                also help us answer the question of which form to submit.
            </p></div>

            <div class="example-contents"><p>
                Let&#039;s create our controller, and add a method for retrieving a
                form instance:
            </p></div>

            <pre class="programlisting brush: php">
class RegistrationController extends Zend_Controller_Action
{
    protected $_form;

    public function getForm()
    {
        if (null === $this-&gt;_form) {
            $this-&gt;_form = new My_Form_Registration();
        }
        return $this-&gt;_form;
    }
}
</pre>


            <div class="example-contents"><p>
                Now, let&#039;s add some functionality for determining which form to
                display. Basically, until the entire form is considered valid,
                we need to continue displaying form segments. Additionally, we
                likely want to make sure they&#039;re in a particular order: user,
                demog, and then lists. We can determine what data has been
                submitted by checking our session namespace for particular keys
                representing each subform.
            </p></div>

            <pre class="programlisting brush: php">
class RegistrationController extends Zend_Controller_Action
{
    // ...

    protected $_namespace = &#039;RegistrationController&#039;;
    protected $_session;

    /**
     * Get the session namespace we&#039;re using
     *
     * @return Zend_Session_Namespace
     */
    public function getSessionNamespace()
    {
        if (null === $this-&gt;_session) {
            $this-&gt;_session =
                new Zend_Session_Namespace($this-&gt;_namespace);
        }

        return $this-&gt;_session;
    }

    /**
     * Get a list of forms already stored in the session
     *
     * @return array
     */
    public function getStoredForms()
    {
        $stored = array();
        foreach ($this-&gt;getSessionNamespace() as $key =&gt; $value) {
            $stored[] = $key;
        }

        return $stored;
    }

    /**
     * Get list of all subforms available
     *
     * @return array
     */
    public function getPotentialForms()
    {
        return array_keys($this-&gt;getForm()-&gt;getSubForms());
    }

    /**
     * What sub form was submitted?
     *
     * @return false|Zend_Form_SubForm
     */
    public function getCurrentSubForm()
    {
        $request = $this-&gt;getRequest();
        if (!$request-&gt;isPost()) {
            return false;
        }

        foreach ($this-&gt;getPotentialForms() as $name) {
            if ($data = $request-&gt;getPost($name, false)) {
                if (is_array($data)) {
                    return $this-&gt;getForm()-&gt;getSubForm($name);
                    break;
                }
            }
        }

        return false;
    }

    /**
     * Get the next sub form to display
     *
     * @return Zend_Form_SubForm|false
     */
    public function getNextSubForm()
    {
        $storedForms    = $this-&gt;getStoredForms();
        $potentialForms = $this-&gt;getPotentialForms();

        foreach ($potentialForms as $name) {
            if (!in_array($name, $storedForms)) {
                return $this-&gt;getForm()-&gt;getSubForm($name);
            }
        }

        return false;
    }
}
</pre>


            <div class="example-contents"><p>
                The above methods allow us to use notations such as &quot;<strong class="command">$subForm =
                    $this-&gt;getCurrentSubForm();</strong>&quot; to retrieve the current
                sub form for validation, or &quot;<strong class="command">$next =
                    $this-&gt;getNextSubForm();</strong>&quot; to get the next one to
                display.
            </p></div>

            <div class="example-contents"><p>
                Now, let&#039;s figure out how to process and display the various sub
                forms. We can use  <span class="methodname">getCurrentSubForm()</span> to determine
                if any sub forms have been submitted (<b><tt>FALSE</tt></b> return values
                indicate none have been displayed or submitted), and
                 <span class="methodname">getNextSubForm()</span> to retrieve a form to display. We
                can then use the form&#039;s  <span class="methodname">prepareSubForm()</span> method to
                ensure the form is ready for display.
            </p></div>

            <div class="example-contents"><p>
                When we have a form submission, we can validate the sub form,
                and then check to see if the entire form is now valid. To do
                these tasks, we&#039;ll need additional methods that ensure that
                submitted data is added to the session, and that when validating
                the form entire, we validate against all segments from the
                session:
            </p></div>

            <pre class="programlisting brush: php">
class RegistrationController extends Zend_Controller_Action
{
    // ...

    /**
     * Is the sub form valid?
     *
     * @param  Zend_Form_SubForm $subForm
     * @param  array $data
     * @return bool
     */
    public function subFormIsValid(Zend_Form_SubForm $subForm,
                                   array $data)
    {
        $name = $subForm-&gt;getName();
        if ($subForm-&gt;isValid($data)) {
            $this-&gt;getSessionNamespace()-&gt;$name = $subForm-&gt;getValues();
            return true;
        }

        return false;
    }

    /**
     * Is the full form valid?
     *
     * @return bool
     */
    public function formIsValid()
    {
        $data = array();
        foreach ($this-&gt;getSessionNamespace() as $key =&gt; $info) {
            $data[$key] = $info;
        }

        return $this-&gt;getForm()-&gt;isValid($data);
    }
}
</pre>


            <div class="example-contents"><p>
                Now that we have the legwork out of the way, let&#039;s build the
                actions for this controller. We&#039;ll need a landing page for the
                form, and then a &#039;process&#039; action for processing the form.
            </p></div>

            <pre class="programlisting brush: php">
class RegistrationController extends Zend_Controller_Action
{
    // ...

    public function indexAction()
    {
        // Either re-display the current page, or grab the &quot;next&quot;
        // (first) sub form
        if (!$form = $this-&gt;getCurrentSubForm()) {
            $form = $this-&gt;getNextSubForm();
        }
        $this-&gt;view-&gt;form = $this-&gt;getForm()-&gt;prepareSubForm($form);
    }

    public function processAction()
    {
        if (!$form = $this-&gt;getCurrentSubForm()) {
            return $this-&gt;_forward(&#039;index&#039;);
        }

        if (!$this-&gt;subFormIsValid($form,
                                   $this-&gt;getRequest()-&gt;getPost())) {
            $this-&gt;view-&gt;form = $this-&gt;getForm()-&gt;prepareSubForm($form);
            return $this-&gt;render(&#039;index&#039;);
        }

        if (!$this-&gt;formIsValid()) {
            $form = $this-&gt;getNextSubForm();
            $this-&gt;view-&gt;form = $this-&gt;getForm()-&gt;prepareSubForm($form);
            return $this-&gt;render(&#039;index&#039;);
        }

        // Valid form!
        // Render information in a verification page
        $this-&gt;view-&gt;info = $this-&gt;getSessionNamespace();
        $this-&gt;render(&#039;verification&#039;);
    }
}
</pre>


            <div class="example-contents"><p>
                As you&#039;ll notice, the actual code for processing the form is
                relatively simple. We check to see if we have a current sub form
                submission, and if not, we go back to the landing page. If we do
                have a sub form, we attempt to validate it, redisplaying it if
                it fails. If the sub form is valid, we then check to see if the
                form is valid, which would indicate we&#039;re done; if not, we
                display the next form segment. Finally, we display a
                verification page with the contents of the session.
            </p></div>

            <div class="example-contents"><p>
                The view scripts are very simple:
            </p></div>

            <pre class="programlisting brush: php">
&lt;?php // registration/index.phtml ?&gt;
&lt;h2&gt;Registration&lt;/h2&gt;
&lt;?php echo $this-&gt;form ?&gt;

&lt;?php // registration/verification.phtml ?&gt;
&lt;h2&gt;Thank you for registering!&lt;/h2&gt;
&lt;p&gt;
    Here is the information you provided:
&lt;/p&gt;

&lt;?
// Have to do this construct due to how items are stored in session
// namespaces
foreach ($this-&gt;info as $info):
    foreach ($info as $form =&gt; $data): ?&gt;
&lt;h4&gt;&lt;?php echo ucfirst($form) ?&gt;:&lt;/h4&gt;
&lt;dl&gt;
    &lt;?php foreach ($data as $key =&gt; $value): ?&gt;
    &lt;dt&gt;&lt;?php echo ucfirst($key) ?&gt;&lt;/dt&gt;
    &lt;?php if (is_array($value)):
        foreach ($value as $label =&gt; $val): ?&gt;
    &lt;dd&gt;&lt;?php echo $val ?&gt;&lt;/dd&gt;
        &lt;?php endforeach;
       else: ?&gt;
    &lt;dd&gt;&lt;?php echo $this-&gt;escape($value) ?&gt;&lt;/dd&gt;
    &lt;?php endif;
    endforeach; ?&gt;
&lt;/dl&gt;
&lt;?php endforeach;
endforeach ?&gt;
</pre>


            <div class="example-contents"><p>
                Upcoming releases of Zend Framework will include components to
                make multi page forms simpler by abstracting the session and
                ordering logic. In the meantime, the above example should serve
                as a reasonable guideline on how to accomplish this task for
                your site.
            </p></div>
        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.form.i18n.html">Internationalization of Zend_Form</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.form.html">Zend_Form</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.gdata.html">Zend_Gdata</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.form.html">Zend_Form</a></li>
  <li><a href="zend.form.introduction.html">Zend_Form</a></li>
  <li><a href="zend.form.quickstart.html">Zend_Form Quick Start</a></li>
  <li><a href="zend.form.elements.html">Creating Form Elements Using Zend_Form_Element</a></li>
  <li><a href="zend.form.forms.html">Creating Forms Using Zend_Form</a></li>
  <li><a href="zend.form.decorators.html">Creating Custom Form Markup Using Zend_Form_Decorator</a></li>
  <li><a href="zend.form.standardElements.html">Standard Form Elements Shipped With Zend Framework</a></li>
  <li><a href="zend.form.standardDecorators.html">Standard Form Decorators Shipped With Zend Framework</a></li>
  <li><a href="zend.form.i18n.html">Internationalization of Zend_Form</a></li>
  <li class="active"><a href="zend.form.advanced.html">Advanced Zend_Form Usage</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>